home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / include / dev / pdev.h < prev    next >
C/C++ Source or Header  |  1989-06-15  |  13KB  |  331 lines
  1. /*
  2.  * pdev.h --
  3.  *
  4.  *    Declarations of the kernel/user-level-server interface for
  5.  *    pseudo-devices. A pseudo-device is a file
  6.  *    whose semantics are implemented by a user-level server process.
  7.  *    All other processes act on the file normally.  Their operations
  8.  *    on the file are mapped by the kernel into a request-response
  9.  *    exchange with the server process.  The types and constants defined
  10.  *    here are needed by the server programs to implement their
  11.  *    half of the pseudo-device protocol.  As well as implement the
  12.  *    regular file operations, Fs_Read, Fs_Write, and Fs_IOControl,
  13.  *    the server is involved in open/close time actions, and the
  14.  *    server helps control the select state of the pseudo device.
  15.  *    
  16.  *    A more complete explaination of pseudo-devices should be in
  17.  *    the man page (/sprite/doc/ref/devices/pdev), but the following
  18.  *    brief explaination may help.  The interface between the kernel
  19.  *    and the server process is based on filesystem streams.  The
  20.  *    server gets a "control stream" when it opens the pseudo-device
  21.  *    file with the FS_MASTER flag.  This control stream is readable
  22.  *    when a new client process has opened the pseudo-device.  The
  23.  *    control stream contains a short message with a new filesystem
  24.  *    streamID for a "service stream" that the server uses to communicate
  25.  *    with the new client.
  26.  *    Service streams are used by the server to get request messages
  27.  *    (that correspond to client operations) and return results.
  28.  *
  29.  *    Associated with each service stream is a "request buffer".  The server
  30.  *    gets request messages from clients indirectly; the requests are
  31.  *    placed into the request buffer, along with their data, and the server
  32.  *    learns about new requests by reading messages from the service stream
  33.  *    that contain 'firstByte' and 'lastByte' offsets into the request buffer.
  34.  *    This buffered interface lets the kernel stack up many requests (writes,
  35.  *    in particular) before a    context switch is required to the server
  36.  *    program.  Of course, this also lets the server handle all the queued
  37.  *    requests at one time.  When the    server has handled requests it updates
  38.  *    the 'firstByte' pointer by making a IOC_PDEV_SET_PTRS ioctl() on
  39.  *    the service stream.
  40.  *
  41.  *    There can also be a read ahead buffer associated with each service
  42.  *    stream.  This is filled with data by the server program that is to
  43.  *    be read by a client, and the kernel moves data from this buffer,
  44.  *    which is again in the server's address space, to the client without
  45.  *    having to switch out to the server process. 
  46.  *    
  47.  * Copyright 1987 Regents of the University of California
  48.  * All rights reserved.
  49.  * Permission to use, copy, modify, and distribute this
  50.  * software and its documentation for any purpose and without
  51.  * fee is hereby granted, provided that the above copyright
  52.  * notice appear in all copies.  The University of California
  53.  * makes no representations about the suitability of this
  54.  * software for any purpose.  It is provided "as is" without
  55.  * express or implied warranty.
  56.  *
  57.  *
  58.  * $Header: /sprite/src/lib/include/dev/RCS/pdev.h,v 1.17 89/06/15 12:15:06 brent Exp $ SPRITE (Berkeley)
  59.  */
  60.  
  61. #ifndef _PDEV
  62. #define _PDEV
  63.  
  64. #include "proc.h"
  65. #ifdef KERNEL
  66. #include "fs.h"
  67. #else
  68. #include <kernel/fs.h>
  69. #endif
  70.  
  71. /*
  72.  * Pseudo-device operations
  73.  *    PDEV_OPEN        The first request after a client open.
  74.  *    PDEV_DUP        OBSOLETE, but might resurrect itself.
  75.  *    PDEV_CLOSE        The last request.
  76.  *    PDEV_READ        Read data from the pseudo-device.
  77.  *    PDEV_WRITE        Write data to the pseudo-device.
  78.  *    PDEV_IOCTL        Special operation on the pseudo-device.
  79.  *    PDEV_WRITE_ASYNC    Asynchronous write.  No reply needed.
  80.  *
  81.  * These two only apply to pseudo-device connections to pseudo-file-systems.
  82.  * For regular pseudo-devices the kernel takes care of attribute handling.
  83.  *    PDEV_GET_ATTR        Get attributes given a pdev connection.
  84.  *    PDEV_SET_ATTR        Set attributes given a pdev connection.
  85.  */
  86.  
  87. typedef int Pdev_Op;
  88.  
  89. #define PDEV_OPEN        1
  90. /* #define PDEV_DUP        2 */
  91. #define PDEV_CLOSE        3
  92. #define PDEV_READ        4
  93. #define PDEV_WRITE        5
  94. #define PDEV_IOCTL        6
  95. #define PDEV_WRITE_ASYNC    7
  96. #define PDEV_GET_ATTR        8
  97. #define PDEV_SET_ATTR        9
  98.  
  99. /*
  100.  * A pseudo-device server gets a 'control stream' when opening a pseudo-device.
  101.  * The following structure describes the messages read from the control stream.
  102.  * Control stream messages are used to notify the server that it
  103.  * has a new private stream because a client opened the pseudo-device.
  104.  */
  105. typedef struct Pdev_Notify {
  106.     unsigned int    magic;            /* == PDEV_NOTIFY_MAGIC */
  107.     int            newStreamID;
  108.     int            reserved;        /* Extra */
  109. } Pdev_Notify;
  110.  
  111. #define PDEV_NOTIFY_MAGIC    0x1D4E4F52
  112.  
  113. /*
  114.  * The first message on a private stream is a PDEV_OPEN.
  115.  * This message identifies the client process, its host, and the host's
  116.  * byte order to the server.
  117.  */
  118.  
  119. typedef struct Pdev_OpenParam {
  120.     int flags;            /* Flags from the Fs_Open call */
  121.     Proc_PID pid;        /* Client's process ID */
  122.     int hostID;            /* Host ID where client is from */
  123.     int uid;            /* User ID of the client process */
  124.     int gid;            /* Group ID of the client process */
  125.     int byteOrder;        /* Byte order identifier */
  126.     int reserved;        /* Extra */
  127. } Pdev_OpenParam;
  128.  
  129. /*
  130.  * PDEV_READ, PDEV_WRITE request parameters, see <kernel/fsIO.h>
  131.  */
  132.  
  133. typedef Fs_IOParam Pdev_RWParam;
  134.  
  135. /*
  136.  * PDEV_IOCTL request parameter, see <kernel/fsIO.h>
  137.  */
  138.  
  139. typedef Fs_IOCParam Pdev_IOCParam;
  140.  
  141. /*
  142.  * PDEV_SET_ATTR request parameters.  These are in the Pdev_Request header,
  143.  * and the new Fs_Attributes record is passed as the data block following
  144.  * the header.  The user and group ID are used for authentication.
  145.  */
  146.  
  147. typedef struct {
  148.     int        flags;        /* Which attributes to set */
  149.     int        uid;        /* User ID */
  150.     int        gid;        /* Group ID */
  151. } Pdev_SetAttrParam;
  152.  
  153.  
  154. /*
  155.  * When a client does something to the pseudo-device the server gets
  156.  * a corresponding request message.  The structure of it is defined here.
  157.  * The control information in the request header is the same for both
  158.  * pseudo-device and pseudo-filesystem operations.
  159.  */
  160.  
  161. typedef struct {
  162.     unsigned int magic;        /* PDEV_REQUEST_MAGIC or PFS_REQUEST_MAGIC */
  163.     Pdev_Op    operation;    /* What action is requested. */
  164.     int        messageSize;    /* The complete size of the request header
  165.                  * plus data, plus padding for alignment */
  166.     int        requestSize;    /* Size of data following this header */
  167.     int        replySize;    /* Max size of the reply data expected. */
  168.     int        dataOffset;    /* Offset of data from start of header */
  169. } Pdev_RequestHdr;
  170.  
  171. typedef struct {
  172.     Pdev_RequestHdr    hdr;    /* with PDEV_REQUEST_MAGIC */
  173.     union {            /* Additional parameters to the operation. */
  174.     Pdev_OpenParam        open;
  175.     Pdev_RWParam        read;
  176.     Pdev_RWParam        write;
  177.     Pdev_IOCParam        ioctl;
  178.     Pdev_SetAttrParam    setAttr;
  179.     } param;
  180. } Pdev_Request;
  181.  
  182. #define PDEV_REQUEST_MAGIC    0x7265717E
  183.  
  184. /*
  185.  * IOC_PDEV_REPLY is used to return the following information about
  186.  * a reply to a client's request.  The status in
  187.  * the reply header will be the return value of the client's system call,
  188.  * except for FS_WOULD_BLOCK and FS_LOOKUP_REDIRECT which are processed
  189.  * by the kernel.
  190.  */
  191.  
  192. typedef struct Pdev_Reply {
  193.     unsigned int magic;        /* PDEV_REPLY_MAGIC */
  194.     ReturnStatus status;    /* Return status of remote call */
  195.     int        selectBits;    /* Return select state bits */
  196.     int        replySize;    /* Size of the data in replyBuf, if any */
  197.     Address    replyBuf;    /* Server space address of reply data */
  198.     int        signal;        /* Signal to return, if non-zero */
  199.     int        code;        /* Code to modify signal */
  200. } Pdev_Reply;
  201.  
  202. #define PDEV_REPLY_MAGIC    0x52455057
  203.  
  204. /*
  205.  * IOC_PDEV_SMALL_REPLY uses the following struct to return a small
  206.  * amount of data to the client's request.
  207.  * Up to PDEV_SMALL_DATA_LIMIT bytes can be returned.
  208.  * 
  209.  */
  210. #define PDEV_SMALL_DATA_LIMIT    16
  211.  
  212. typedef struct Pdev_ReplyData {
  213.     unsigned int magic;        /* PDEV_REPLY_DATA_MAGIC */
  214.     ReturnStatus status;    /* Return status of remote call */
  215.     int        selectBits;    /* Return select state bits */
  216.     int        replySize;    /* Size of following data */
  217.     Address    replyBuf;    /* Unused, needed for padding & compatibility */
  218.     int        signal;        /* (non-zero) Signal to generate, if any */
  219.     int        code;        /* Code to modify the signal */
  220.     char    data[PDEV_SMALL_DATA_LIMIT];    /* Reply data */
  221. } Pdev_ReplyData;
  222.  
  223. #define PDEV_REPLY_DATA_MAGIC    0x524ABC57
  224.  
  225. /*
  226.  * I/O Controls for server streams.
  227.  *    IOC_PDEV_READY        The server uses this to notify the kernel
  228.  *                that the pseudo-device is ready for I/O now.
  229.  *                The input buffer should contain an int
  230.  *                with an or'd combination of FS_READABLE,
  231.  *                FS_WRITABLE, or FS_EXCEPTION.
  232.  *    IOC_PDEV_SET_BUF    These are used to tell the kernel where the
  233.  *                request buffer and read ahead buffer (if any)
  234.  *                are. The input buffer should contain a
  235.  *                Pdev_SetBufArgs struct.  Note that this
  236.  *                needs to be done after getting a notification
  237.  *                on the control stream before any request
  238.  *                (i.e. the client's open request) comes through.
  239.  *                This can also be done later to change the
  240.  *                buffer if needed.  The buffer change takes
  241.  *                place as soon as the previous one empties.
  242.  *                The switch is indicated by the requestAddr
  243.  *                that you read from the service stream.
  244.  *    IOC_PDEV_WRITE_BEHIND    Set (Unset) write-behind buffering in the
  245.  *                request buffer.  The single input argument
  246.  *                is a pointer to a Boolean; TRUE enables
  247.  *                write-behind, FALSE inhibits it.  The default
  248.  *                is no write-behind.
  249.  *    IOC_PDEV_SET_PTRS    These are used to update the firstByte and
  250.  *                lastByte pointers into the request and
  251.  *                read ahead buffers.  The input buffer
  252.  *                is a Pdev_BufPtrs structure.
  253.  *    IOC_PDEV_REPLY        This is used to send a reply to a request.
  254.  *                The input buffer contains a Pdev_Reply.  This
  255.  *                includes an address (in the server's space)
  256.  *                of a buffer containing reply data, if any.
  257.  *    IOC_PDEV_SMALL_REPLY    This is like IOC_PDEV_REPLY, except that
  258.  *                the reply data is embedding in the struct
  259.  *                passed into the kernel.  The amount of data
  260.  *                that can be returned this was is defined
  261.  *                by PDEV_SMALL_DATA_LIMIT.
  262.  *    IOC_PDEV_BIG_WRITES    Set (Unset) the ability of the client to
  263.  *                write a chunk larger than will fit into
  264.  *                the request buffer.  This is to support
  265.  *                UDP socket semantics that prevent a client
  266.  *                from writing more than the declared packet size.
  267.  *                (Of course, we could do better by keeping the
  268.  *                 existing semantics that automatically break
  269.  *                 the write into smaller ones...)
  270.  *                The input buffer should reference a Boolean;
  271.  *                TRUE enables big writes (which is the default)
  272.  *                FALSE prevents big writes.
  273.  *    IOC_PDEV_SIGNAL_OWNER    This sends a signal to the controlling process
  274.  *                of the pseudo-device.  If there is no owner
  275.  *                then this is ignored.  The input buffer contains
  276.  *                the signal number and code to send.
  277.  *
  278.  */
  279.  
  280. #define IOC_PDEV        (2 << 16)
  281. #define IOC_PDEV_READY        (IOC_PDEV | 0x1)
  282. #define IOC_PDEV_SET_BUF    (IOC_PDEV | 0x2)
  283. #define IOC_PDEV_WRITE_BEHIND    (IOC_PDEV | 0x3)
  284. #define IOC_PDEV_SET_PTRS    (IOC_PDEV | 0x4)
  285. #define IOC_PDEV_REPLY        (IOC_PDEV | 0x5)
  286. #define IOC_PDEV_BIG_WRITES    (IOC_PDEV | 0x6)
  287. #define IOC_PDEV_SIGNAL_OWNER    (IOC_PDEV | 0x7)
  288. #define IOC_PDEV_SMALL_REPLY    (IOC_PDEV | 0x8)
  289.  
  290. /*
  291.  * Input structure for the IOC_PDEV_SET_BUF IOControl
  292.  */
  293.  
  294. typedef struct Pdev_SetBufArgs {
  295.     Address    requestBufAddr;        /* Server's address of request buffer */
  296.     int        requestBufSize;        /* Num bytes in the request buffer */
  297.     Address    readBufAddr;        /* NULL if no read ahead.  Non-NULL
  298.                      * implicitly enables read-ahead. */
  299.     int        readBufSize;        /* Num bytes in the read ahead buffer */
  300. } Pdev_SetBufArgs;
  301.  
  302. /*
  303.  * Input structure for IOC_PDEV_SET_PTRS IOControl.
  304.  */
  305.  
  306. typedef struct Pdev_BufPtrs {
  307.     int magic;            /* == PDEV_BUF_PTR_MAGIC */
  308.     Address    requestAddr;    /* The address of the request buffer.  This is
  309.                  * valid when reading only, and it indicates
  310.                  * what request buffer is being used.  See
  311.                  * IOC_PDEV_SET_BUF. */
  312.     int requestFirstByte;    /* Byte offset of the first valid data byte
  313.                  * in the request buffer.  If -1 buf is empty */
  314.     int requestLastByte;    /* Byte offset of the last valid data byte. */
  315.     int readFirstByte;        /* Byte offset of the first valid data byte
  316.                  * in the read ahead buffer. -1 => empty */
  317.     int readLastByte;        /* Byte offset of the last data byte. */
  318. } Pdev_BufPtrs;
  319.  
  320. #define PDEV_BUF_PTR_MAGIC    0x3C46DF14
  321.  
  322. /*
  323.  * Stucture for the IOC_PDEV_SIGNAL_OWNER operation.
  324.  */
  325. typedef struct Pdev_Signal {
  326.     unsigned int signal;
  327.     unsigned int code;
  328. } Pdev_Signal;
  329.  
  330. #endif _PDEV
  331.